<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libcoap: coap_resource(3)</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">libcoap<span id="projectnumber">&#160;4.2.0</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.8 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('man_coap_resource.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">coap_resource(3)</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>coap_resource</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /></head><body><div xml:lang="en" class="refentry" lang="en"><a id="id1337"></a><div class="titlepage"></div><div class="refnamediv"><h2>NAME</h2><p>coap_resource, coap_resource_init, coap_resource_unknown_init, coap_add_resource, coap_delete_resource, coap_delete_all_resources, coap_resource_set_mode — Work with CoAP resources</p></div><div class="refsynopsisdiv"><a id="_synopsis"></a><h2>SYNOPSIS</h2><p><span class="strong"><strong>#include &lt;coap2/coap.h&gt;</strong></span></p><p><span class="strong"><strong>coap_resource_t *coap_resource_init(coap_str_const_t *<span class="emphasis"><em>uri_path</em></span>,
int <span class="emphasis"><em>flags</em></span>);</strong></span></p><p><span class="strong"><strong>coap_resource_t *coap_resource_unknown_init(coap_method_handler_t
<span class="emphasis"><em>put_handler</em></span>);</strong></span></p><p><span class="strong"><strong>void coap_add_resource(coap_context_t *<span class="emphasis"><em>context</em></span>,
coap_resource_t *<span class="emphasis"><em>resource</em></span>);</strong></span></p><p><span class="strong"><strong>int coap_delete_resource(coap_context_t <span class="emphasis"><em>context</em></span>,
coap_resource_t <span class="emphasis"><em>resource</em></span>);</strong></span></p><p><span class="strong"><strong>void coap_delete_all_resources(coap_context_t *<span class="emphasis"><em>context</em></span>);</strong></span></p><p><span class="strong"><strong>void coap_resource_set_mode(coap_resource_t *<span class="emphasis"><em>resource</em></span>, int <span class="emphasis"><em>mode</em></span>);</strong></span></p><p>Link with <span class="strong"><strong>-lcoap-2</strong></span>, <span class="strong"><strong>-lcoap-2-gnutls</strong></span>,
<span class="strong"><strong>-lcoap-2-openssl</strong></span> or
<span class="strong"><strong>-lcoap-2-tinydtls</strong></span> depending on your (D)TLS library
type.</p></div><div class="refsect1"><a id="_description"></a><h2>DESCRIPTION</h2><p>CoAP Resources on a CoAP Server need to be created and updated etc. The URI in
the request packet defines the resource to work with, with possibly the Query
referring to a sub-resource.</p><p>When resources are configured on the CoAP server, the URI to match against
in the request packet is specified.</p><p>Callback Handlers are then added to the resource to handle the different
request methods.</p><p>Adding Attributes allows textual information to be added to the resource
which can then be reported back to any client doing a "GET .well-known/core"
request.</p><p>If an incoming packet request matches a resource’s URI and Method, then
the appropriate callback resource handler is invoked to process the packet
which then should update a suitable response packet for sending back to the
requester.</p><p>There is support for handling incoming packets where the URI is unknown.
This could, for example, happen when a PUT request is trying to create a new
resource. It is the responsibility of the unknown resource callback handler
to either create a new resource for the URI or just manage things separately.</p><p>CoAP Observe (RFC 7641) is not supported for unknown resources, so a new
resource with GET handler must be created by the unknown resource callback
handle matching the URI which then can be Observable.</p><p>The <span class="strong"><strong>coap_resource_init</strong></span>() function returns a newly created <span class="emphasis"><em>resource</em></span> of
type <span class="emphasis"><em>coap_resource_t</em></span> * .  <span class="emphasis"><em>uri_path</em></span> specifies the uri string path to match
against.  <span class="emphasis"><em>flags</em></span> is used to define whether the
<span class="emphasis"><em>resource</em></span> is of type Confirmable Message or Non-Confirmable Message for
any "observe" responses.  See <a href="man_coap_observe.html" target="_self"><span class="strong"><strong>coap_observe</strong></span>(3)</a>.
<span class="emphasis"><em>flags</em></span> can be one of the following definitions or’ed together.</p><div class="horizontal"><table class="horizontal" cellpadding="4px" style="border: none;"><colgroup><col /><col /></colgroup><tbody valign="top"><tr><td style="" valign="top">
<p>
<span class="strong"><strong>COAP_RESOURCE_FLAGS_NOTIFY_NON</strong></span>
</p>
</td><td style="" valign="top">
<p>
Set the notification message type to non-confirmable for any trigggered
"observe" responses.
</p>
</td></tr><tr><td style="" valign="top">
<p>
<span class="strong"><strong>COAP_RESOURCE_FLAGS_NOTIFY_CON</strong></span>
</p>
</td><td style="" valign="top">
<p>
Set the notification message type to confirmable for any trigggered
"observe" responses.
</p>
</td></tr><tr><td style="" valign="top">
<p>
<span class="strong"><strong>COAP_RESOURCE_FLAGS_RELEASE_URI</strong></span>
</p>
</td><td style="" valign="top">
<p>
Free off the coap_str_const_t for <span class="emphasis"><em>uri_path</em></span> when the <span class="emphasis"><em>resource</em></span> is deleted.
</p>
</td></tr></tbody></table></div><p><span class="strong"><strong>NOTE:</strong></span> <span class="emphasis"><em>uri_path</em></span>, if not 7 bit readable ASCII, binary bytes must be hex
encoded according to the rules defined in RFC3968 Section 2.1.</p><p>The <span class="strong"><strong>coap_resource_unknown_init</strong></span>() returns a newly created <span class="emphasis"><em>resource</em></span> of
type <span class="emphasis"><em>coap_resource_t</em></span> *. <span class="emphasis"><em>put_handler</em></span> is automatically added to the
<span class="emphasis"><em>resource</em></span> to handle PUT requests to resources that are unknown. Additional
handlers can be added to this resource if required.</p><p>The <span class="strong"><strong>coap_add_resource</strong></span>() function registers the given <span class="emphasis"><em>resource</em></span> with the
<span class="emphasis"><em>context</em></span>. The <span class="emphasis"><em>resource</em></span> must have been created by <span class="strong"><strong>coap_resource_init</strong></span>(),
or <span class="strong"><strong>coap_resource_unknown_init</strong></span>(). The storage allocated for the <span class="emphasis"><em>resource</em></span>
will be released by <span class="strong"><strong>coap_delete_resource</strong></span>().</p><p>As the <span class="emphasis"><em>uri_path</em></span> of the resource has to be unique across all of the resources
associated with a <span class="emphasis"><em>context</em></span>, <span class="strong"><strong>coap_add_resource</strong></span>() (or
<span class="strong"><strong>coap_add_resource_release</strong></span>()) will delete any previous
<span class="emphasis"><em>resource</em></span> with the same <span class="emphasis"><em>uri_path</em></span> before adding in the new <span class="emphasis"><em>resource</em></span>.</p><p>The <span class="strong"><strong>coap_delete_resource</strong></span>() function deletes a <span class="emphasis"><em>resource</em></span> identified by
<span class="emphasis"><em>resource</em></span> from <span class="emphasis"><em>context</em></span>. The storage allocated for that <span class="emphasis"><em>resource</em></span> is freed,
along with any attrigutes associated with the <span class="emphasis"><em>resource</em></span>.</p><p>The <span class="strong"><strong>coap_delete_all_resources</strong></span>() function deletes all resources from
<span class="emphasis"><em>context</em></span> and frees their storage.</p><p>The <span class="strong"><strong>coap_resource_set_mode</strong></span>() changes the notification message type of
<span class="emphasis"><em>resource</em></span> to the given <span class="emphasis"><em>mode</em></span> which must be one of
COAP_RESOURCE_FLAGS_NOTIFY_NON or COAP_RESOURCE_FLAGS_NOTIFY_CON.</p></div><div class="refsect1"><a id="_return_values"></a><h2>RETURN VALUES</h2><p>The <span class="strong"><strong>coap_resource_init</strong></span>() and <span class="strong"><strong>coap_resource_unknown_init</strong></span>() functions
return a newly created resource or NULL if there is a malloc failure.</p><p>The <span class="strong"><strong>coap_delete_resource</strong></span>() function return 0 on failure (<span class="emphasis"><em>resource</em></span> not
found), 1 on success.</p></div><div class="refsect1"><a id="_examples"></a><h2>EXAMPLES</h2><p><span class="strong"><strong>Fixed Resources Set Up</strong></span></p><pre class="programlisting">#include &lt;coap2/coap.h&gt;

#define INDEX "This is an example server using libcoap\n"

void
hnd_get_index(coap_context_t *ctx, coap_resource_t *resource,
coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
coap_string_t *query, coap_pdu_t *response) {
  unsigned char buf[3];

  response-&gt;code = COAP_RESPONSE_CODE(205);

  coap_add_option(response,
                  COAP_OPTION_CONTENT_TYPE,
                  coap_encode_var_safe(buf, sizeof(buf),
                                       COAP_MEDIATYPE_TEXT_PLAIN),
                  buf);

  coap_add_option(response,
                  COAP_OPTION_MAXAGE,
                  coap_encode_var_safe(buf, sizeof(buf), 0x2ffff), buf);

  coap_add_data(response, strlen(INDEX), (const uint8_t *)INDEX);

}

void
hnd_delete_time(coap_context_t *ctx, coap_resource_t *resource,
coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
coap_string_t *query, coap_pdu_t *response) {

  /* .. code .. */

}

void
hnd_get_time(coap_context_t *ctx, coap_resource_t *resource,
coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
coap_string_t *query, coap_pdu_t *response) {

  /* .. code .. */

}

void
hnd_put_time(coap_context_t *ctx, coap_resource_t *resource,
coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
coap_string_t *query, coap_pdu_t *response) {

  /* .. code .. */

}

static void
init_resources(coap_context_t *ctx) {

  coap_resource_t *r;

  /* Create a resource to return general information */
  r = coap_resource_init(NULL, 0);
  coap_register_handler(r, COAP_REQUEST_GET, hnd_get_index);

  /* Document resource for .well-known/core request */
  coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0);
  coap_add_attr(r, coap_make_str_const("title"),
                coap_make_str_const("\"General Info\""), 0);

  coap_add_resource(ctx, r);

  /* Create a resource to return return or update time */
  r = coap_resource_init(coap_make_str_const("time"),
                         COAP_RESOURCE_FLAGS_NOTIFY_CON);
  coap_resource_set_get_observable(r, 1);
  coap_register_handler(r, COAP_REQUEST_GET, hnd_get_time);
  coap_register_handler(r, COAP_REQUEST_PUT, hnd_put_time);
  coap_register_handler(r, COAP_REQUEST_DELETE, hnd_delete_time);

  /* Document resource for .well-known/core request */
  coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0);
  coap_add_attr(r, coap_make_str_const("title"),
                coap_make_str_const("\"Internal Clock\""), 0);
  coap_add_attr(r, coap_make_str_const("rt"), coap_make_str_const("\"secs\""),
                0);
  coap_add_attr(r, coap_make_str_const("if"), coap_make_str_const("\"clock\""),
                0);

  coap_add_resource(ctx, r);

}</pre><p><span class="strong"><strong>Dynamic Resources Set Up</strong></span></p><pre class="programlisting">#include &lt;coap2/coap.h&gt;

/* Regular DELETE handler - used by resources created by the
 * Unknown Resource PUT handler */

void
hnd_delete(coap_context_t *ctx, coap_resource_t *resource,
coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
coap_string_t *query, coap_pdu_t *response) {

  /* .. code .. */

  /* Dynamic resource no longer required - delete it */
  coap_delete_resource(ctx, resource);

}

/* Regular GET handler - used by resources created by the
 * Unknown Resource PUT handler */

void
hnd_get(coap_context_t *ctx, coap_resource_t *resource,
coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
coap_string_t *query, coap_pdu_t *response) {

  coap_str_const_t *get_uri_path;
  coap_string_t *get_query;
  coap_opt_iterator_t opt_iter;
  coap_opt_filter_t filter;
  coap_opt_t *option;
  int len;

  /*
   * request will be NULL if an Observe triggered request, so the uri_path,
   * if needed, must be abstracted from the resource.
   * The uri_path string is a const pointer
   */

  get_uri_path = coap_resource_get_uri_path(resource);
  get_query = query;

  /* .. code .. */

}

/* Regular PUT handler - used by resources created by the
 * Unknown Resource PUT handler */

void
hnd_put(coap_context_t *ctx, coap_resource_t *resource,
coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
coap_string_t *query, coap_pdu_t *response) {

  coap_string_t *put_uri_path;

  /* get the uri_path */
  put_uri_path = coap_get_uri_path(request);
  if (!put_uri_path) {
    response-&gt;code = COAP_RESPONSE_CODE(404);
    return;
  }

  /* .. code .. */

  /* Need to do this as coap_get_uri_path() created it */
  coap_delete_string(put_uri_path);

}

/* Unknown Resource PUT handler */

void
hnd_unknown_put(coap_context_t *ctx, coap_resource_t *resource,
coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
coap_string_t *query, coap_pdu_t *response) {

  coap_resource_t *r;
  int len;
  coap_string_t *uri_path;

  /* get the uri_path - which will get used by coap_resource_init() */
  uri_path = coap_get_uri_path(request);
  if (!uri_path) {
    response-&gt;code = COAP_RESPONSE_CODE(404);
    return;
  }

  /* Check if new URI Path is valid */
  if (!check_url_fn (uri_path, request-&gt;code)) {
    response-&gt;code = COAP_RESPONSE_CODE(404);
    coap_delete_string(uri_path);
    return;
  }

  /*
   * Create a resource to handle the new URI
   * uri_path will get deleted when the resource is removed
   */
  r = coap_resource_init((coap_str_const_t*)uri_path,
        COAP_RESOURCE_FLAGS_RELEASE_URI | COAP_RESOURCE_FLAGS_NOTIFY_NON);
  coap_register_handler(r, COAP_REQUEST_PUT, hnd_put);
  coap_register_handler(r, COAP_REQUEST_DELETE, hnd_delete);
  /* We possibly want to Observe the GETs */
  coap_resource_set_get_observable(r, 1);
  coap_register_handler(r, COAP_REQUEST_GET, hnd_get);
  coap_add_resource(ctx, r);

  /* Do the PUT for this first call */
  hnd_put(ctx, r, session, request, token, query, response);

  return;

}

/* Initialize single Unknown Resource PUT handler */

static void
init_resources(coap_context_t *ctx) {

  coap_resource_t *r;

  /* Create a resource to handle PUTs to unknown URIs */
  r = coap_resource_unknown_init(hnd_unknown_put);
  /*
   * Additional handlers can be added - for example
   *  coap_register_handler(r, COAP_REQUEST_POST, hnd_post_unknown);
   *  coap_register_handler(r, COAP_REQUEST_GET, hnd_get_unknown);
   *  coap_register_handler(r, COAP_REQUEST_DELETE, hnd_delete_unknown);
   */
  coap_add_resource(ctx, r);

}</pre></div><div class="refsect1"><a id="_see_also"></a><h2>SEE ALSO</h2><p><a href="man_coap_attribute.html" target="_self"><span class="strong"><strong>coap_attribute</strong></span>(3)</a>, <a href="man_coap_context.html" target="_self"><span class="strong"><strong>coap_context</strong></span>(3)</a>, <a href="man_coap_observe.html" target="_self"><span class="strong"><strong>coap_observe</strong></span>(3)</a> and <a href="man_coap_handler.html" target="_self"><span class="strong"><strong>coap_handler</strong></span>(3)</a></p></div><div class="refsect1"><a id="_further_information"></a><h2>FURTHER INFORMATION</h2><p>See "RFC7252: The Constrained Application Protocol (CoAP)" for further
information.</p></div><div class="refsect1"><a id="_bugs"></a><h2>BUGS</h2><p>Please report bugs on the mailing list for libcoap:
<a class="ulink" href="mailto:libcoap-developers@lists.sourceforge.net" target="_top">libcoap-developers@lists.sourceforge.net</a></p></div><div class="refsect1"><a id="_authors"></a><h2>AUTHORS</h2><p>The libcoap project &lt;<a class="ulink" href="mailto:libcoap-developers@lists.sourceforge.net" target="_top">libcoap-developers@lists.sourceforge.net</a>&gt;</p></div></div></body></html> coap_resource(3)</p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Fri Dec 27 2024 09:57:44 for libcoap by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.8 </li>
  </ul>
</div>
</body>
</html>
